home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 25 / AMIGAplus Sonderheft 25 (2000)(Falke)(DE)(Track 1 of 4)[!].iso / Tools / SFX-Player / Mpeg / mpega_library / developer / mpega.doc
Text File  |  2000-05-08  |  8KB  |  220 lines
  1. TABLE OF CONTENTS
  2.  
  3. mpega/MPEGA_close
  4. mpega/MPEGA_decode_frame
  5. mpega/MPEGA_find_sync
  6. mpega/MPEGA_open
  7. mpega/MPEGA_seek
  8. mpega/MPEGA_time
  9. mpega/MPEGA_close                                           mpega/MPEGA_close
  10.  
  11.    NAME
  12.         MPEGA_close -- close an MPEG Audio stream.
  13.  
  14.    SYNOPSIS
  15.         MPEGA_close( mpega_stream );
  16.                           a0
  17.  
  18.         void MPEGA_close( MPEGA_STREAM * );
  19.  
  20.    FUNCTION
  21.         Closes an MPEG Audio stream. Once this call has been made, the
  22.         stream can no longer be accessed.
  23.  
  24.    INPUTS
  25.         mpega_stream - the MPEG Audio stream to close.
  26.  
  27.    RESULT
  28.  
  29.    SEE ALSO
  30.         MPEGA_open()
  31.  
  32.    BUGS
  33.  
  34. mpega/MPEGA_decode_frame                             mpega/MPEGA_decode_frame
  35.  
  36.    NAME
  37.         MPEGA_decode_frame -- Decode one frame of MPEG Audio stream.
  38.  
  39.    SYNOPSIS
  40.         sample_count = MPEGA_decode_frame( mpega_stream, pcm );
  41.              d0                                 a0       a1
  42.  
  43.         LONG MPEGA_decode_frame( MPEGA_STREAM *, WORD *pcm[ MPEGA_MAX_CHANNELS ] );
  44.  
  45.    FUNCTION
  46.         This function decodes one frame of MPEG Audio stream. Decoded audio
  47.         samples are stored in given pcm buffers (16-bit samples). The function
  48.         returns the number of decoded samples (for one channel) or an error code
  49.         (negative number). The maximum number of decoded samples will not exceed
  50.         MPEGA_PCM_SIZE. The number of samples depend on the MPEG Audio stream
  51.         type (norm and layer) and on the decoded frequency output division.
  52.         The channel 0 is Left or Mono, channel 1 is Right.
  53.  
  54.    INPUTS
  55.         mpega_stream - Opened MPEG Audio stream obtain from MPEGA_open()
  56.         pcm - Array of MPEGA_MAX_CHANNELS buffers of MPEGA_PCM_SIZE WORD's.
  57.  
  58.    RESULT
  59.         pcm - These arrays will be filled with audio pcm samples if sample_count > 0.
  60.         sample_count - number of samples decoded for each channel. This number
  61.             may be 0 if current frame was skipped because decoder is not yet
  62.             synchronized, this is * NOT * a decoding error.
  63.             If this number is < 0, end of stream is reached (= MPEGA_ERR_EOF)
  64.             or an error was found (MPEGA_ERR_BADFRAME).
  65.  
  66.    SEE ALSO
  67.         MPEGA_open(), MPEGA_close()
  68.  
  69.    BUGS
  70.  
  71. mpega/MPEGA_find_sync                                   mpega/MPEGA_find_sync
  72.  
  73.    NAME
  74.         MPEGA_find_sync -- Find an MPEG Audio sync word in a buffer.
  75.  
  76.    SYNOPSIS
  77.         sync_pos = MPEGA_find_sync( buffer, buffer_size );
  78.            d0                         a0         d0
  79.  
  80.         LONG MPEGA_find_sync( BYTE *, LONG );
  81.  
  82.    FUNCTION
  83.         This function searches for an MPEG Audio sync word in a buffer.
  84.         You can use this function to see if a file contains MPEG Audio data.
  85.         If the function returns >= 0 value, a valid MPEG Audio header was found.
  86.  
  87.    INPUTS
  88.         buffer - BYTE buffer to watch
  89.         buffer_size - Number of bytes of given buffer
  90.  
  91.    RESULT
  92.         sync_pos - sync postion of a valid MPEG Audio frame or MPEGA_ERR_NO_SYNC
  93.             if no valid frame found.
  94.  
  95.    SEE ALSO
  96.  
  97.    BUGS
  98.  
  99. mpega/MPEGA_open                                             mpega/MPEGA_open
  100.  
  101.    NAME
  102.         MPEGA_open -- Open an MPEG Audio stream.
  103.  
  104.    SYNOPSIS
  105.         mpega_stream = MPEGA_open( stream_name, ctrl );
  106.              d0                         A0       a1
  107.  
  108.         MPEGA_STREAM *MPEGA_open( char *, MPEGA_CTRL * );
  109.  
  110.    FUNCTION
  111.         Opens an MPEG Audio stream and returns an mpeg audio stream structure.
  112.         The stream name is the MPEG Audio filename if standard file access is used.
  113.         The ctrl structure controls the stream access and the decoding
  114.         parameters. If you want a standard file access to the streams, set the
  115.         bs_access field of MPEGA_CTRL to NULL. Otherwise, set it to a pointer
  116.         to a Hook that specifies your custom access to the stream. It this case,
  117.         your Hook function will be called in this way:
  118.  
  119.          ULONG __saveds __asm HookFunc( register __a0 struct Hook  *hook,
  120.                                         register __a2 APTR          handle,
  121.                                         register __a1 MPEGA_ACCESS *access );
  122.  
  123.          MPEGA_ACCESS struct specifies bitstream access function & parameters
  124.  
  125.          access->func == MPEGA_BSFUNC_OPEN
  126.             open the bitstream
  127.             access->data.open.buffer_size is the i/o block size your read function can use
  128.             access->data.open.stream_size is the total size of the current stream
  129.                                           (in bytes, set it to 0 if unknown)
  130.             return your file handle (or NULL if failed)
  131.          access->func == MPEGA_BSFUNC_CLOSE
  132.             close the bitstream
  133.             return 0 if ok
  134.          access->func == MPEGA_BSFUNC_READ
  135.             read bytes from bitstream.
  136.             access->data.read.buffer is the destination buffer.
  137.             access->data.read.num_bytes is the number of bytes requested for read.
  138.             return # of bytes read or 0 if EOF.
  139.          access->func == MPEGA_BSFUNC_SEEK
  140.             seek into the bitstream
  141.             access->data.seek.abs_byte_seek_pos is the absolute byte position to reach.
  142.             return 0 if ok
  143.  
  144.         Control structure contains Layers decoding settings, one for Layers I & II and
  145.         one for Layer III (which is more CPU intensive). These settings controls the
  146.         audio quality, the output frequency division and the stereo to mono conversion.
  147.         Control structure allows also to choose the stream buffer size, which set the
  148.         amount of bytes read for stream in a block.
  149.         For more details about this structure see <libraries/mpega.h> .
  150.  
  151.         If the returned value is NULL, the stream can't be opened (if it's not an
  152.         MPEG Audio stream for example). Otherwise, mpega_stream (read only) contains
  153.         informations about current stream and actual decoding values.
  154.  
  155.     INPUTS
  156.         stream_name - Name of the stream to open.
  157.         ctrl - Decoding control.
  158.  
  159.     RESULTS
  160.         mpega_stream - The stream structure, use it to get information about
  161.             current stream. You should pass this to other functions.
  162.  
  163.     SEE ALSO
  164.         MPEGA_close(), MPEGA_decode_frame()
  165.  
  166.     BUGS
  167.  
  168. mpega/MPEGA_seek                                             mpega/MPEGA_seek
  169.  
  170.    NAME
  171.         MPEGA_seek -- Seek into an MPEG Audio stream.
  172.  
  173.    SYNOPSIS
  174.         error = MPEGA_seek( mpega_stream, ms_time_position );
  175.           d0                     a0              d0
  176.  
  177.         LONG MPEGA_seek( MPEGA_STREAM *, ULONG );
  178.  
  179.    FUNCTION
  180.         This function allows to seek into an opened stream. The seek
  181.         position is a time position in milliseconds. If the seek failed,
  182.         the function returns an error (MPEGA_ERR_EOF if outside of stream).
  183.  
  184.     INPUTS
  185.         mpega_stream - Opened MPEG Audio stream obtain from MPEGA_open()
  186.         ms_time_position - Time position of seek.
  187.  
  188.     RESULT
  189.         error - 0 if Ok or < 0 if error (see MPEGA_ERR_xxx)
  190.  
  191.     SEE ALSO
  192.         MPEGA_time()
  193.  
  194.  
  195. mpega/MPEGA_time                                             mpega/MPEGA_time
  196.  
  197.    NAME
  198.         MPEGA_time -- Get the current time position of an MPEG Audio stream
  199.  
  200.    SYNOPSIS
  201.         error = MPEGA_time( mpega_stream, ms_time_position );
  202.           d0                     a0             a1
  203.  
  204.         LONG MPEGA_time( MPEGA_STREAM *, ULONG * );
  205.  
  206.    FUNCTION
  207.         This function gets the current time position of an opened stream.
  208.         The return time position is given in milliseconds.
  209.  
  210.     INPUTS
  211.         mpega_stream - Opened MPEG Audio stream obtain from MPEGA_open()
  212.  
  213.     RESULT
  214.         ms_time_position - Current time position.
  215.         error - 0 if Ok or < 0 if error (see MPEGA_ERR_xxx)
  216.  
  217.     SEE ALSO
  218.         MPEGA_seek()
  219.  
  220.